Aminet 44/Aminet 44 (2001)(GTI - Schatztruhe)[!][Aug 2001].iso/Aminet/comm/misc/Spitfire2.lha/Spitfireｲ Install/developer/spitfireAPI.doc

Text File | 2000-03-27 | 14KB | 757 lines

TABLE OF CONTENTS

spitfireAPI.library/---overview---
spitfireAPI.library/Spit_AddUser
spitfireAPI.library/Spit_CloseUsersFile
spitfireAPI.library/Spit_FirstUser
spitfireAPI.library/Spit_GetActiveUser
spitfireAPI.library/Spit_GetClientSig
spitfireAPI.library/Spit_GetEnvPath
spitfireAPI.library/Spit_GetNotifyEvent
spitfireAPI.library/Spit_GetNotifySig
spitfireAPI.library/Spit_GetSystemID
spitfireAPI.library/Spit_GetUserID
spitfireAPI.library/Spit_GetUserName
spitfireAPI.library/Spit_GetUserPassword
spitfireAPI.library/Spit_GetUserPath
spitfireAPI.library/Spit_GetUserPos
spitfireAPI.library/Spit_GotoUser
spitfireAPI.library/Spit_LastUser
spitfireAPI.library/Spit_NextUser
spitfireAPI.library/Spit_NotifyClients
spitfireAPI.library/Spit_NotifyServer
spitfireAPI.library/Spit_NumberUsers
spitfireAPI.library/Spit_OpenUsersFile
spitfireAPI.library/Spit_PrevUser
spitfireAPI.library/Spit_ReadEvent
spitfireAPI.library/Spit_RegisterClient
spitfireAPI.library/Spit_RegisterServer
spitfireAPI.library/Spit_RemoveClient
spitfireAPI.library/Spit_RemoveServer
spitfireAPI.library/Spit_SaveUsersFile
spitfireAPI.library/Spit_SetActiveUser
spitfireAPI.library/Spit_SetEnvPath
spitfireAPI.library/Spit_SetSystemID
spitfireAPI.library/Spit_SetUserID
spitfireAPI.library/Spit_SetUserName
spitfireAPI.library/Spit_SetUserPassword
spitfireAPI.library/Spit_SetUserPath
spitfireAPI.library/Spit_Wait4Event


 spitfireAPI.library/---overview---             spitfireAPI.library/---overview---

   SPITFIRE² DESKTOP CLIENTS

        Spitfire² clients need to communicate with the HSM program. This is
        done through the spitfireAPI.library. The client needs to call
        Spit_RegisterClient() in order to receive messages from HSM.  When
        existing, the client needs to remove itself with a call to
        Spit_RemoveClient().

        A client may look like this:

            client = Spit_RegisterClient();
                ...
                Spit_WaitForEvent(client);
                Spit_ReadEvent(client,&event,&data);
                ...
            Spit_RemoveClient(client);

        More often though, you will want to listen to other ports as well,
        for instance that of a window:

            client = Spit_RegisterClient();
                ...
                mask = (1<<Spit_GetClientSig(client))|(1<<windowsigbit);
                Wait(mask);
                Spit_ReadEvent(client,&event,&data);
                ...
            Spit_RemoveClient(client);



   EVENT CODES

        HSM broadcasts the following event codes:

           SPIT_QUIT

                If your client receives SPIT_QUIT, remove it as soon as
                possible.

           SPIT_SHOWINTERFACE

                When this message is broadcast, the client should open its
                window.

           SPIT_HIDEINTERFACE

                When this message is broadcast, the client should close
                its window and anything similar.

           SPIT_SAVEDB

                A broadcase of this message means that HSM is in HotSync
                mode, and your application should save all data in order
                for the conduit to synchronize the data.

           SPIT_LOADDB

                This event is usually broadcast once HotSyncing is done,
                thus your application should reload and update its data.

           SPIT_NEWUSERS

                This event indicates a new user has been added to the user
                list.  You should update your applications user list as
                soon as possible.


 spitfireAPI.library/Spit_AddUser                spitfireAPI.library/Spit_AddUser

   NAME
        Spit_AddUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_CloseUsersFile         spitfireAPI.library/Spit_CloseUsersFile

   NAME
        Spit_CloseUsersFile -- ends access to an opened users.dat file

   SYNOPSIS
        success = Spit_CloseUserFile(userlist)
        D0                           D0

        LONG Spit_CloseUser(APTR);

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_FirstUser              spitfireAPI.library/Spit_FirstUser

   NAME
        Spit_FirstUser --

   SYNOPSIS
        = Spit_FirstUser(userlist)

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetActiveUser          spitfireAPI.library/Spit_GetActiveUser

   NAME
        Spit_GetActiveUser --

   SYNOPSIS
        = Spit_GetActiveUser(userlist)

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetClientSig           spitfireAPI.library/Spit_GetClientSig

   NAME
        Spit_GetClientSig -- get the signal of a client port

   SYNOPSIS
        signal = Spit_GetClientSig(client)
        D0                      D0

        UBYTE Spit_GetClientSig(APTR);

   FUNCTION
        This function returns the signal that will be set when a message
        arrives at the given client's message port. Using a Wait() for
        this signal is somewhat more useful than using Spit_WaitForEvent(),
        as this will let you listen to other signals as well.

   INPUTS
        client - a pointer to the client whose signal you wish to obtain.

   RESULT
        signal - the number of the signal associated with the given
                 client's port.

   SEE ALSO
        Spit_ReadEvent(), Spit_WaitForEvent()

 spitfireAPI.library/Spit_GetEnvPath             spitfireAPI.library/Spit_GetEnvPath

   NAME
        Spit_GetEnvPath --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetNotifyEvent         spitfireAPI.library/Spit_GetNotifyEvent

   NAME
        Spit_GetNotifyEvent --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetNotifySig           spitfireAPI.library/Spit_GetNotifySig

   NAME
        Spit_GetNotifySig --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetSystemID            spitfireAPI.library/Spit_GetSystemID

   NAME
        Spit_GetSystemID --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetUserID              spitfireAPI.library/Spit_GetUserID

   NAME
        Spit_GetUserID --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetUserName            spitfireAPI.library/Spit_GetUserName

   NAME
        Spit_GetUserName --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetUserPassword        spitfireAPI.library/Spit_GetUserPassword

   NAME
        Spit_GetUserPassword --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetUserPath            spitfireAPI.library/Spit_GetUserPath

   NAME
        Spit_GetUserPath --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GetUserPos             spitfireAPI.library/Spit_GetUserPos

   NAME
        Spit_GetUserPos --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_GotoUser               spitfireAPI.library/Spit_GotoUser

   NAME
        Spit_GotoUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_LastUser               spitfireAPI.library/Spit_LastUser

   NAME
        Spit_LastUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_NextUser               spitfireAPI.library/Spit_NextUser

   NAME
        Spit_NextUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_NotifyClients          spitfireAPI.library/Spit_NotifyClients

   NAME
        Spit_NotifyClients --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_NotifyServer           spitfireAPI.library/Spit_NotifyServer

   NAME
        Spit_NotifyServer -- notify the HSM server of an event

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_NumberUsers            spitfireAPI.library/Spit_NumberUsers

   NAME
        Spit_NumberUsers --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_OpenUsersFile          spitfireAPI.library/Spit_OpenUsersFile

   NAME
        Spit_OpenUsersFile --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_PrevUser               spitfireAPI.library/Spit_PrevUser

   NAME
        Spit_PrevUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_ReadEvent              spitfireAPI.library/Spit_ReadEvent

   NAME
        Spit_ReadEvent -- receive a message from the server

   SYNOPSIS
        success = Spit_ReadEvent(client,event,data)
        D0                    A0     D1    D0

        ULONG Spit_ReadEvent(APTR,ULONG *,ULONG *);

   FUNCTION
        This function reads a message from the client's message port. If a
        message exists, it will copy the event and data codes into the
        addresses provided by the caller, and dispose of the message.

        You should keep calling this function until it returns FALSE, as
        several messages might arrive at the port simultaneously.

   INPUTS
        client - the client whose port to check.
        event - pointer to a longword in which to store the event code of
                the message, if there is one.
        data - ditto for the data code.

   RESULT
        success - TRUE if there was a message, in which case the longwords
                  pointed to by the event and data fields will contain the
                  info broadcast by the message, FALSE if there was no
                  message.

   SEE ALSO


 spitfireAPI.library/Spit_RegisterClient         spitfireAPI.library/Spit_RegisterClient

  NAME
        Spit_RegisterClient -- create a Spitfire² message client

   SYNOPSIS
        client = Spit_RegisterClient()
        D0

        APTR Spit_RegisterClient(void);

   FUNCTION
        This function creates a client of with the HSM message server. A
        Spitfire² client should call this in order to receive messages from
        the HSM through the Spit_ReadEvent() call.

        The message server must be active before any clients can be
        created. If it is not, this function will fail. Normally, clients
        will be launched by the DAM after the HSM server has been created, so
        this should not be a problem.

   RESULT
        client - a pointer to a Spitfire² message client structure, or FALSE
                 if the client could not be created.

   SEE ALSO
        Spit_RemoveClient(), Spit_ReadEvent()


 spitfireAPI.library/Spit_RegisterServer         spitfireAPI.library/Spit_RegisterServer

   NAME
        Spit_RegisterServer --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_RemoveClient           spitfireAPI.library/Spit_RemoveClient

   NAME
        Spit_RemoveClient -- destroy a KRSNAke message client

   SYNOPSIS
        success = Spit_RemoveClient(client)
        D0                       D0

        ULONG Spit_RemoveClient(APTR);

   FUNCTION
        This function detaches a client from the server and destroys it.
        All clients created by the Spit_RegisterClient() function must be
        disposed of with this function.

   INPUTS
        client - a pointer to a client returned from the
                 Spit_RegisterClient() function.

   RESULT
        success - TRUE if the client was removed, FALSE otherwise.

   SEE ALSO
        Spit_RegisterClient()


 spitfireAPI.library/Spit_RemoveServer           spitfireAPI.library/Spit_RemoveServer

   NAME
        Spit_RemoveServer --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SaveUsersFile          spitfireAPI.library/Spit_SaveUsersFile

   NAME
        Spit_SaveUsersFile --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetActiveUser          spitfireAPI.library/Spit_SetActiveUser

   NAME
        Spit_SetActiveUser --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetEnvPath             spitfireAPI.library/Spit_SetEnvPath

   NAME
        Spit_SetEnvPath --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetSystemID            spitfireAPI.library/Spit_SetSystemID

   NAME
        Spit_SetSystemID --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetUserID              spitfireAPI.library/Spit_SetUserID

   NAME
        Spit_SetUserID --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetUserName            spitfireAPI.library/Spit_SetUserName

   NAME
        Spit_SetUserName --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetUserPassword        spitfireAPI.library/Spit_SetUserPassword

   NAME
        Spit_SetUserPassword --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_SetUserPath            spitfireAPI.library/Spit_SetUserPath

   NAME
        Spit_SetUserPath --

   SYNOPSIS

   FUNCTION

   INPUTS

   RESULT

   SEE ALSO


 spitfireAPI.library/Spit_Wait4Event             spitfireAPI.library/Spit_Wait4Event

   NAME
        Spit_WaitForEvent -- wait for a message to arrive at a client's port

   SYNOPSIS
        success = Spit_WaitForEvent(client)
        D0                       D0

        ULONG Spit_WaitForEvent(APTR);

   FUNCTION
        This function calls WaitPort() for the given client's port, which
        causes the calling task to wait until the client receives a
        message from the server.

   INPUTS
        client - the client whose port to wait on.

   RESULT
        success - TRUE if the wait succeeded, FALSE otherwise. At present,
                  the FALSE return value only happens if you pass a NULL
                  client pointer.

   SEE ALSO
        Spit_GetClientSig(), Spit_ReadEvent()